The REDCAMEL Approach for Designing APIs

Introduction#

We’re going to use the REDCAMEL approach in the coming chapters as we design various APIs. We’ll expand on the REDCAMEL approach in the following sections.

Requirements (RE)#

In the requirements lessons, we identify the functional and non-functional requirements of the API to be designed. This helps us identify the functionalities we need to address while designing an API. Further, we also mention the prerequisite concepts a learner would need to know before designing an API. The structure of the requirements lesson contains the following sections:

• Introduction or motivation: This section briefly defines the problem and its motivation.

• Functional requirements: In this section, we identify the essential API functional requirements that we’ll focus on in the API model phase.

• Non-functional requirements: Here, we focus on the non-functional requirements crucial for our API to work smoothly.

• Prerequisites: In this section, we list the concepts learners should understand before moving toward the design of API.

• Chapter structure: Here, we give an overview of the lessons in the rest of the chapter.

The following illustration demonstrates the section we focus on in the requirements lesson:

Design considerations (DC)#

In the design considerations lessons, we make some technical decisions based on the services involved in a system and the client interaction with them. We mainly divide these lessons into the following sections:

• Design overview and workflow: In this section, we give an overview and workflow of the system for which we aim to design an API.

• API architecture styles: Here, we decide which architecture style to use between the client, API gateway, and back-end servers.

• Data formats: This section focuses on the data formats to use for exchanging data between different entities. For example, we decide between JSON, XML, binary, or any other data type.

• Protocols and their versions: Here, we opt for suitable protocols and their versions that suit our requirements and needs for data communication between clients and servers.

The structure of the design consideration lessons is shown in the following figure:

API model (AM)#

In the API model lessons, we define multiple endpoints to perform various operations to meet functional requirements. Following our decisions in the design consideration phase, we present each operation's request and response structure by accessing the endpoint corresponding to each operation. We exchange data between the client and server in the formats we decide on in the design consideration phase.

Overall, we have the following sections in the lesson on the API model:

• Base URL and API endpoints: Here, we define the base URL for our API and related endpoints for each service. We also present essential data entities that can be a part of the request, response, or both.

• Data entities: This section highlights the data elements required for a particular design problem.

• The request-response format of each operation: This section focuses on each operation's request and response format.

• Failed requests statuses: At the end of the lesson, we present failed request status codes that can occur if any request processing fails.

The structure of the API model lessons is depicted below:

Evaluation and latency budget (EL)#

We divide the final lesson of each design problem into two major sections: evaluation of the non-functional requirements and latency budget.

• Evaluation of non-functional requirements: In this first section, we describe the techniques we chose to meet the non-functional requirements of the API, such as scalability, availability, low latency, security, and so on.

• Latency budget: In this section, we estimate the latency of our API in light of the numbers we derived in the lesson on back-of-the-envelope calculations. The estimated latency is then used to calculate the final response time of an API.

The structure of the evaluation and latency budget lessons is shown below: